<?php

/** This collection of functions (libary) is licensed under GPL2.
 *  See LICENSE or www.gnu.org for more details.
 *
 *  This package contains all Dataxi error types and error classes.
 *
 *  Adding a new type of error
 *  --------------------------
 *  1) Add a new type for an error. Add it to the DZER_* defines, those
 *  starting with '#'. For example, define(DZER_MYERROR, "#99"). The actual
 *  error no. (type) is 99, but the define must have the '#' prefix.
 *
 *  2) Add the actual error message text in dzerror.msg for the new type no.
 *      (99)
 *
 *  3) Deside the error level of the error, see DZERL_* defines for
 *  more.
 *
 *  4) Deside the error type the error, see DZERT_* defines for more.
 *
 *  5) Deside the recovery action type of the error, see DZREC_* for more.
 *
 *  5) Create a dzErrorMsg() object. The constructor takes a lot of
 *  parameters, like the rror level, type and so. The $Msg passed may be a
 *  string to display as the error message or "#xx" that refers to a message
 *  stored in dzerror.msg file. The $Module is optional and may be used to
 *  specify the the program module name (string) that produced the error -
 *  used basically only by system errors.
 *  $Params is a soSet object that contains possible replacement texts
 *  for tags in error text, if any. Say, the error text is "This error is
 *  [severity] [type]", then a good soSet for the dzErrorMsg could be build
 *  like this: $params = new soSet(); $params->addItem("severity", "really");
 *  $params->addItem("type", "bad");. So, the final error text displayed
 *  would be "This error is really bad". Note, that this tag replacement
 *  is not necessary if the error texts is not fetched from the dzerror.msg.
 *
 *  6) Add the newly created dzErroMsg object to the sessions error log:
 *  $SesData->ErrorLog->add($error_msg)
 *
 *
 *  Author: Henri Ranki 2.2.2002
 *
 *  Dataxi error handling functions and data structures.
 *
 *  $Id: dzerror.php,v 1.11 2005/03/12 17:06:52 jyry Exp $
 */

include_once("sodebug.php");
include_once("sostring.php");
include_once("solist.php");
include_once("dzconst.php");


/** Error codes
 *  Define error codes here. Arror messages are located in message db
 *  in dzerror.msg. Note it is preferable to use error codes instead
 *  of hard coded messages altough it is possible. Message codes are
 *  prefixed with hash (#).
 */
define(DZER_GENERAL, "#1");
define(DZER_NO_BROWSE_ROWS, "#2");  /** No browse rows were found with given
                                        conditions */
define(DZER_WRITE_FAILED, "#3");  /** Writeing to database failed */
define(DZER_READ_ERROR, "#4");  /** Reading the data set failed */
define(DZER_KONE_RPC_FAILED, "#5");  /** Rpc to kone failed */
define(DZER_DELETE_FAILED, "#6");  /** Deleting from database failed */
define(DZER_QUERY_FAILED, "#7");  /** Quering from database failed */
define(DZER_LOCK_RELEASE_FAILED, "#8");  /** Releasing the locks
                                             failed failed */
define(DZER_RPC_SUBARI_FAILED, "#9");  /** Subari RPC failed*/
define(DZER_TABLE_VALIDATE_FAILED, "#10");  /** Field value was not found
                                            in the defined table */
define(DZER_SRC_PARSE_FAILED, "#11");  /** Parsing of the src failed */
define(DZER_SRC_CACHE_WRITE_FAILED, "#12");  /** Writeing cache failed */
define(DZER_FETCH_FAILED, "#13");  /** Fetch request failed */
define(DZER_ACCESS_UPD_FAILED, "#14");  /** Updating access time */
define(DZER_PASSWORD_MISMATCH, "#15");  /** The password did not match
                                            after suspend */
define(DZER_FORM_CREATE, "#16");  /** Creating the form failed */
define(DZER_SET_VALIDATION_FAILED, "#17"); /** Set validation failed */
define(DZER_SET_VALIDATION_FAILED_MULTIROW, "#18"); /** Set validation failed */
define(DZER_UNIQUE_CHECK_FAILED, "#19"); /* Unique check failed */
define(DZER_REQUIRED_CHECK_FAILED, "#20"); /* Required check failed */
define(DZER_PRESAVE_FAILED, "#21"); /* Presave failed */

/** Error levels
 */
define(DZERL_NOTIFY, 1);    /** Some minor things that might be worth of
                                telling to user */
define(DZERL_WARNING, 2);   /** Message about some strange behavior or
                                situation */
define(DZERL_ERROR, 3);     /** Error situation that needs user actions */
define(DZERL_FATAL, 4);     /** Fatal error that usually causes terminating
                                the session or atleast the view */


/** Error types
 *  This tells who is the person who should be notified. Also tells
 *  at which level the error occurred and what level caused it.
 *  e.g. Was the error due to erronous dataxi form side or was it caused
 *  by wrong behavior of the end user.
 */
define(DZERT_USER, 1);    /** The end user did something funny/stupid */
define(DZERT_SOURCE, 2);  /** This dataxi application has something wrong.
                              typically errors in dataxi forms or its
                              settings */
define(DZERT_SYSTEM, 3);    /** The system experienced problems.
                                e.g. This might be losing the network
                                connection */
define(DZERT_INTERNAL, 4);  /** More serious system problem. The system
                                run into situation that was never supposed
                                to happen. To solve it, tears and sweat is
                                typically needed.*/


/** Recovery action type defines
 * Define different actions that is needed to recover from the error.
 *
 */
define(DZREC_NO_ACTION, 0);     /** No special action is needed. Just notify. */
define(DZREC_KILL_VIEW, 1);     /** Remove the current view that caused the error.
                                   The error was so fatal that the wiew cannot
                                   be returned. */
define(DZREC_KILL_SESSION, 2);  /** Terminate the whole session. Usually in
                                    conjuction with fatal errors that cannot
                                    be solved */



/** Error data structure
 *  When Dataxi encounters an error it fils in a data structure of this type.
 *  Later all encountered error are handled in specific state in state
 *  machine.
 *
 *  @var string $Text The message string that can contain tags. Tag format is:
 *      [tag_name]. tags are replaced with information in the $Params property.
 *      This can be also a reference to error database. To reference to error
 *      database (dzerror.msg) set the error code prefixed with hash (#) here.
 *      e.g. #47. Error database is in dzerror.ini
 *  @var soSet/string $Params Parameters for the message. Tags in the message
 *      string are replaced with this data. The of to soSet is the tag name.
 *  @var string $Module The module that caused the error
 *  @var int $Recover Recovery action. Should the view or the session be
 *      terminated. See defines in dzconst.php
 *  @var int $Type Type of the error. (What type? --jq)
 *  @var int $Level Level of the error. See the begining of this file for
 *      different types,
 *  @var
 */
class dzErrorMsg {
    var $Text;
    var $Params;
    var $Module;
    var $Recover = 0;
    var $Type;
    var $Level;


    /** Constructor
     *  @param string $Msg Error msg no. or string ("#05" or "error text")
     *  @param string $Module The module causing the error
     *  @param DZERT_* $Type Type of the error.
     *  @param DZERL_* $Level Severity of the error.
     *  @param DZREC_* $Recover Should the session be terminated (?)
     *  @param soSet $Params (not used???)
     */
    function dzErrorMsg($Msg = "", $Module = "", $Type = 0,
                        $Level = 0, $Recover = 0, $Params = NULL) {
        $this->Text = $Msg;
        $this->Module = $Module;
        $this->Type = $Type;
        $this->Level = $Level;
        $this->Recover = $Recover;
        $this->Params = $Params;
    } // constructor

} // dzErrorMsg


/** Error log
 * Class that logs all errors during one request to dataxi.
 * Dataxi takes care of errors later at the end of the state machine.
 */
class dzError {
    var $Recover;     /**int The most radical recovery action that is needed
                            among the occurred errors. e.g. Terminating session
                            also includes terminating of the all views. */
    var $__Messages;  /**soList/dzErrorMsg  List of errors occurred during
                                 processing the request. */

    /** constructor
     */
    function dzError() {
        $this->__Messages = new soList();
    } // constructor


    /** Add new arror to error log.
     *  @param object dzErrorMsg $Msg The filled error msg structure
     */
    function add($Msg) {
        soDebug("dzError: add error msg:".$Msg->Text, SOD_DET);

        /* The most radical recovery action is performed. */
        $this->Recover = max($Msg->Recover, $this->Recover);

        $this->__Messages->insItem($Msg);
    } // add


    /** Deletes an error message from the error log
     *  @param int $Index index of the message to delete
     */
    function delError($Index) {
        $this->__Messages->delItem($Index);
    } // delError


    /** Get an error message at given index
     *  @param int $Index The index of the error to get
     *  @return dzErrorMsg     The messgae struct or NULL on error
     */
    function getError($Index) {
        if ($Index >= $this->__Messages->count())
            $result = NULL;
        else
            $result = $this->__Messages->getItem($Index);

        return $result;
    } // getError


    /** get the amount of logged errors
     */
    function getErrorCount() {
        return $this->__Messages->count();
    } // getErrorCount
} // dzError


/** Define dataxi system error types */
define(DZSE_INSTALL, "install"); /** Something wrong with dataxi
                                     system's installation */
define(DZSE_NOTIFY, "notify"); /** Notify user about some system
                                  error state. This is caused usually
                                  by user actions. E.g. session hijaak.*/
define(DZSE_SYSTEM, "system"); /** The system run into serious problem */

/** Prints a system error message
 *  These are typically fatal error when some of the system information
 *  was not found or there were problems with write permissions or
 *  serious problems accessing the database.
 *
 * @param string $Msg Message to print
 * @param string $Type Message type
 * @param bool $Die Should the application terminate
 */
function dzSysError($Msg, $Type = DZSE_INSTALL, $Die = 0) {
    soDebug($Msg, SOD_HI_E);
    switch ($Type) {
        case DZSE_INSTALL:
            $TypeMsg = "Dataxi installation error";
            break;

        case DZSE_NOTIFY:
            $TypeMsg = "Notify";
            break;

        case DZSE_SYSTEM:
            $TypeMsg = "System error";
            break;

        default:
            $TypeMsg = "";
    }; // switch

    $Msg = "<hr><b>$TypeMsg!</b><br>$Msg<hr>";
    if ($Die) {
        die($Msg);
    } else {
        echo "$Msg<br>\n";
    } // if
} // dzSysError

?>
